Let’s get started with the first Docker kata. Each kata will be broken into steps. Below each command is a sample of the output that we should see when executing the command. Each step includes, after the commands, a breakdown of the commands and a summary of what they do.

Docker Kata 1 will introduce us to working with containers and images.

Step 1: Run the first container#

The command to run the container is given below.

The output will be something like this:

Running the first container

docker: This is the Docker Engine, which is the core Docker program.

Commands

Parameter

Description

container

Parent commands act on Docker objects such as containers, images, networks, etc.

run

Runs an image, creating an instance of a container.

hello-world

This is an image. The docker run hello-world command in Step 1 ran the hello-world image and an instance of a container was created.

This first command runs a container from an image. A Docker image is a blueprint for a container. Containers are running instances of an image.

The difference between an image and a container is the same as the difference between an executable (such as Notepad.exe) and the running program. Just as multiple instances of Notepad (and most other programs) can run side by side, various containers can be run at the same time, from the same image.

Note the first line of the output:

Unable to find image 'hello-world: latest' locally

Docker will first check the local image repository for the image indicated in the command. If the image is not found, it will check Docker Hub. Docker Hub is a public repository of images maintained by Docker Inc. The hello-world image is a test image stored on Docker Hub.

Image definitions include a start command. The start command runs a process inside the container when an image is run (we’ll work with that in later katas). The start command of the hello-world image echoes the text we see in the output window.

Step 2: List the containers#

The command to list the running containers is provided below.

After running this command, we’ll see output like the following:

Listing running containers

Commands

Parameter

Description

docker container

This is the parent command.

ls

This lists the running containers.

The docker container ls command lists the containers. The first execution, however, returns an empty list. We ran the hello-world container in the first step, so why’s the list empty?

The list is empty because docker container ls only lists running containers. Containers run as long as their start process runs. If that process exits, the container exits. The start command for the hello-world image echoes the output from the first step and then exits immediately. The docker container ls command returns an empty list because no containers are running.

The command to list all the containers is given below.

The output of the command will be something like this:

Listing all containers

Commands

Parameter

Description

docker container

This is the parent command.

ls

This lists the running containers.

-a

This lists all the containers.

The second command includes the -a parameter, which lists all the images, including those that have started and exited.

Step 3: List images#

The command to list all the images is given below.

When we run the command, the output will be something like this:

Listing images

Commands

Parameter

Description

docker image

This is the parent command.

ls

This lists all the images.

This command lists all the images in the local image repository. That will include all the images we’ve downloaded from Docker Hub and any we’ve created ourselves.

Step 4: Run a named container#

The command to name and run a container is given below.

The output will be something like this:

Naming and running the container

Commands

Parameter

Description

container

This is the parent command.

run

This runs a container.

--name

This assigns a name to a container.

my_container

This is the name assigned to the container.

hello-world

This is the name of the image to run.

When running a container, we don’t have to specify a name. The Docker Engine will assign a random one. However, naming containers makes them easier to keep track of when running many at one time. The name assigned with the --name parameter will appear in the container list. That name can then be used to refer to the container in other commands, such as inspect.

The command to list all the containers is given below.

The output of the command above will be something like this:

Listing all containers

Commands

Parameter

Description

container

This is the parent command.

ls

This lists the containers.

-a

This lists all the containers, both running and exited.

It lists all the containers, including the ones running and exited.

The inspect command is given below.

The output will be something like this:

Inspecting the container

Commands

Parameter

Description

container

This is the parent command.

ls

This lists the containers.

-a

This lists all the containers, both running and exited.

The inspect command works on several object types, including containers. When executed on a container object, inspect returns JSON-formatted data that describes the container.

We can also use a container ID to refer to a container when executing a command. The ID is a long string of characters. The first twelve of those characters are listed in the ID column:

devops@DevOpsKatas:~$ docker container ls -a
CONTAINER ID        IMAGE               COMMAND             CREATED       
c91a3a7c8134        hello-world         "/hello"            39 seconds ago
42eddbc93b81        hello-world         "/hello"            37 minutes ago

We can use the first three or more characters to refer to a container (and other objects with IDs):

devops@DevOpsKatas:~$ docker inspect 42e
[
 {
     "Id": "42eddbc93b81ca7c61c9abb385451d673e4e08293086966fa836cfd6e048a145",
     "Created": "2017-03-09T02:02:48.196355507Z",
     "Path": "/hello",
     "Args": [],
     ...

Step 5: Run a container in interactive mode#

The command to run a container in interactive mode is given below.

When we run the command, the output will be something like this:

Running the container in interactive mode

Commands

Parameter

Description

container

This is the parent command.

run

This runs a container.



-it

This represents two separate parameters:

  • The -i part runs the container interactively.
  • The -t part allocates a pseudo-TTY. This is a terminal-like interface between two processes.

Single-character parameters can be combined and prepended by a single dash. Together, the -it parameters allow interactive connection to a container.

ubuntu

This is an image based on the Ubuntu operating system.


bash

The parameter after the image name (ubuntu) is a command to run within the container. In this case, the command is bash. Bash is a shell program used to enter commands into a Linux OS. It’s the program we’re using when we run commands in the terminal window.

Running a container interactively allows a user to connect to the container in a live fashion using a text console interface. This step runs a bash shell in the container, which is the same program we’re using when we enter commands in the terminal window. A container that’s run interactively behaves much like any other remote server. Developers and administrators can view files in the file system, run programs, and install components to the container. This mechanism is useful for debugging, testing, and defining new images.

If we look closely at the prompt in the bash shell console, we’ll see this:

root@e8fedb60e8e6:/#

The first part before the @ sign is the logged-on user. We connect as the root user to the container, which is the administrative superuser of a Unix OS. The second part after the @ sign is the computer name. The name of the container is its container ID:

devops@DevOpsKatas:~$ docker container ls -a
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                      
e8fedb60e8e6        ubuntu              "bash"              2 days ago          Exited (130) 21 minutes ago

The command to list the files and folders is given below.

The output of the command above will be something like this:

Listing files and folders

Command

Command

Description

ls

This lists the files and directories in the container.

The ls command lists the files in the container file system.

The command to list the bin directory is given below.

The output will be something like:

Listing the bin folder

Command

Command

Description

ls /bin

This lists the files and directories in the /bin directory of the container. The files displayed here are Linux commands and programs.

The ls /bin command lists the files in the bin folder.

The command to exit the container is given below.

Command

Command

Description

exit

This closes the pseudo-TTY connection. This also terminates the bash process started when the container was run, so the container exits as well.

The exit command exits the Bash shell running in the container.

Step 6: Remove all the containers and images#

The command to clear all the containers and images is given below.

When we run the command above, the output will be something like this:

Clearing all the containers and images

Commands

Parameter

Description

docker container

This is the parent command.

rm

This removes an object type—in this case, a docker container.




$(docker container ls -a -q)

This is a Unix shell command substitution. The output of this subcommand will be fed to the Docker container `rm` command.

  • ls: This lists the containers.
  • -a: This lists all the containers.
  • -q: This is quiet mode, which returns only the container IDs.

The entire command runs docker container rm once for each output of docker container ls -a -q. The effect is that all the containers on the system are removed.

This is a cleanup step that will be executed between some katas and steps to clear all the images and containers. These won’t be commonly run in a real production environment, given its potential to destroy work.

The command to list all the containers is given below.

When we run this command, the following output will be displayed:

Listing all containers

Commands

Parameter

Description

container

This is the parent command.

ls

This lists the containers.

-a

This lists all the containers.

The listing is empty because all the containers, running and exited, have been removed.

The command to remove images from the local computer is given below.

The output will be something like this:

Removing images from the local computer

Commands

Parameter

Description

image

This is the parent command.

ls

This lists the images.

$(docker image ls -aq)

This is a command substitution that outputs the IDs of every image in the local image repository. Note that the -aq parameters can be combined, similar to -it.

This command removes all the images from the local computer.

Practice commands#

We’ve given a terminal at the end of the lesson and a table containing a list of commands discussed in this lesson. Try out these commands after running the terminal, and check out the results!

Commands

Step

Command

This runs a container from the hello-world image.

docker container run hello-world

This lists all the running containers.

docker container ls

This lists all the containers (running and stopped).

docker container ls -a

This lists all the images.

docker image ls

This runs a container from the hello-world image and assigns it the name my_container.

docker container run --name my_container hello-world

This lists all the containers (running and stopped).

docker container ls -a

This inspects the container named my_container.

docker container inspect my_container

This runs the bash program container in the ubuntu image interactively.

docker container run -it ubuntu bash

This lists the files in the root of the container.

ls

This lists the files in the /bin folder of the container.

ls /bin

This exits the interactive session.

exit

This removes all the containers and images.

docker container rm $(docker container ls -a -q)

This lists all the containers (running and stopped).

docker container ls -a

This removes all the local images.

docker image rm $(docker image ls -aq)

Terminal 1
Terminal

Click to Connect...

Quiz Yourself on Containers and Docker

Docker Kata 2: Disconnected Containers